Merciful 4/Merciful - Disc 4.iso/software/p/psychotoads.dms/psychotoads.adf/a78

Text File | 1989-03-31 | 51KB | 1,675 lines

                         7:CONTROL STRUCTURES                               73
                      --------------------------


                   GOTO (jump to a new line number)

The action of GOTO is to transfer the control of the program one place
to another. There are three forms of the GOTO command allowes in AMOS;

        GOTO label

"label" is an optional place marker at the side of a line. Label names
are defined using the ":" colon character like so:

        label:

The label name can consist of any string of alphanumeric characters you
like, including "-". It's constructed using the same rules which apply
for variables and procedure names.

        GOTO line number

Any AMOS Basic line can be optionally preceded with a number. These
line numbers are included solely for compatibility purposes with other
versions of Basic (such as STOS for the Atari ST). It's better to rely
on labels instead, as these are much easier to read and remember.

        GOTO variable

Variable can be any allowable AMOS Basic expression. This expression
may be either a normal ingerer or a string. Integers run a line number
for your GOTO, whereas strings hold the name of a label.

  Technically speaking, this construction is known as a computed goto.
It's generally growned upon by serious programmers, but it can be
incredibly useful at times. Examples:

        ROOM=3
        BEGIN:
        Goto "ROOM"+Str$(ROOM)-" "
        End
        ROOM3:
        Print "Room three!"
        Goto BEGIN



                     GOSUB (jump to a subroutine)                           74

GOSUB is another outmoded instruction, and provides you with the useful
ability to split a program into smaller, more manageable chunks, known
as subroutines. Nowadays, GOSUB has been almost entirely supplanted by
AMOS Basic's procedure system. However, GOSUB does form a useful
half-way house when you're converting programs from another version of
Basic such as STOS.

  As with GOTO, there are three different forms of the GOSUB
instruction.

        GOSUB n         Jump to the subroutine at line n

        GOSUB name      Jump to an AMOS label

        GOSUB exp       Jump to a label or line which results from the
                        expression in "exp".

        Example:

        For I=1 To 10
          Gosub TEST
        Next I
        Direct
        TEST:
        Print "This is an example of GOSUB":Print "I equals ";I
        Return: Rem Exit from subroutine TEST and return to main prg.

It's good practice to always plave your subroutines at the end of your
main program as this makes them easier to pick out from your program
listings. You should also add a statement like EDIT or DIRECT to end of
your main program, as otherwise AMOS may attempt to execute your GOSUBs
after the program has finished, generating an error message.



                   RETURN (return from a subroutine)

RETURN

RETURN exits from a subroutine which was previously entered using
GOSUB. It immediately jumps back to the next Basic instruction after
the original GOSUB.

  Note that a single GOSUB statement can contain several RETURN
commands. So you can exit from any number of different points in your
routine depending on the situation.



              POP (remove the RETURN info after a GOSUB)                    75

POP

Normally it's illegal to exit from a GOSUB statement using a standard
GOTO. This can occassionally be inconvenient, especially if an error
occurs, which makes in unacceptable to return to your program from the
precice point you left it.

  The POP instruction removes the return address generated by your
GOSUB, and allows you to leave the subroutine in any way you like,
without first having to execute the final RETURN statement. Example:

        Do
          Gosub TEST
        Loop
        BYE:
        Print "Popped Out"
        Direct :
        TEST:
        Print "Hi there!"
        If Mouse Key Then Pop : Goto BYE
        Return




        IF...THEN...[ELSE] (coose between alternative actions)              76

The IF...THEN instruction allows you to make simple decisions within a
Basic program. The format is:

IF conditions THEN statements 1 [ELSE statements 2]

"conditions" can be any list of tests including AND and OR. Statements
1 and Statements 2 must be a list of AMOS Basic instructions. If you
want to jump to a line number or a label, you'll have to include a
separate GOTO command like so:

        If test Then Goto Label : This is fine.
                     ----
If you forget about this, and leave the "Goto", you'll get an error
message "procedure not defined".

        If test Then Label : Rem THIS CALLS A *PROCEDURE*

The scope of this IF...THEN statement is limited to just a single line
of your Basic program. It has now been superceded by the much more
powerful IF...ELSE...ENDIF command.



                 IF...[ELSE]...ENDIF (structured test)

Although the original form of IF...THEN is undoubtedly useful, it's
rather old fashioned when compared with the facilities found in a
really modern version of Basic such as AMOS. This allows you to execute
whole lists of instructions depending on the outcome of a single test.

        IF tests=TRUE
          <List of statements 1>
               "       "
        ELSE
          <List of statements 2>
               "       "
        ENDIF

Note: it's illegal to use a normal IF...THEN inside a structured test!
These should be replaced by their equivalent IF...ENDIF instruction ;

        If test Then Goto Label Else Label2

This now becomes:

        If test : Goto Label : Else goto Label2 : Endif

or:

        If test
          Goto Label
        Endif

Here is an example of the IF...ENDIF statement in action:

        Input "Enter values for a,b and c";A,B,C
        If A=B
          Print "Equal"
        ELSE
          Print "Different";
          If A<>B and A<>C
            Print ", and C is not the same too!"
          Endif
        End if

Each IF statement in your program MUST be paired with a single ENDIF
command as this informs AMOS Basic precisely which group of
instructions are to be executed inside your test.

Note that "THEN" is not used by this form of the instruction at all.
This may take a little getting used to if you are already experienced
with one of the other versions of Basic for the Commodore Amiga.



                FOR...NEXT (repeat a section of a code                      77
                      a specific number of times)

FOR index=first TO last [STEP inc]
<list of instructions>
         "
NEXT [index]

"Index" holds a counter which will be incremented after each and every
loop. At the start of the loop, this counter will be loaded with the
result of the expression "first". The instructions between FOR and the
NEXT are now performed until the NEXT is reached.

  "inc" is a value which will be added to the counter after each loop
by the NEXT instruction. If this is omitted, the increment will be
automatically set to 1.

  Note that if "inc" is negative, the loop will be halted when the
counter is less than the value in "first". So the entire loop will be
performed in reverse.

  Once inside loop, "index" can be read from your program just like a
normal variable. But you are *NOT* allowed to change its value in any
way as this will generate an error message.

  Each FOR statement in your program MUST be matched by a single NEXT
instruction. You can't use the shorthand forms found in other Basics
like NEXT R1,R1. Here are a couple of examples of these loops:

        For I=32 to 255 : Print Chr$(I);:Next I

        For R1=20 to 100 Step 20
          For R2=20 to 100 Step 20
            For A=0 To 3
              Ink A
              Ellipse 160,100,R1,R2
            Next A
          Next R2
        Next R1



                   WHILE...WEND (repeat a section of                        78
                    code while a condition is true)

WHILE condition
  :     :
list of statements
  :     :
WEND

"condition" can be any set of tests you like and can include the
constructions AND, OR and NOT. A check is made on each turn of the
loop. If the test returns a value of -1 (true), then the statements
between the WHILE and WEND will be executed, otherwise the loop will be
aborted and Basic will proceed to the next insturction. Type the
following example:

        Input "Type in a number";X
        Print "Counting to 11"
        While X<11
          Inc X
          Print X
        Wend
        Print "Loop terminated"

The number of times WHILE loop in this program will executed depends on
the value you input to the routine. If you enter a number larger than
10, the loop will never be executed at all. WHILE will therefore only
execute the statements if the condition is TRUE at the start of your
program.



        REPEAT...UNTIL (repeat until a condition is satisfied)

REPEAT
 :  :
list of statements
 :  :
UNTIL condition

REPEAT...UNTIL is similar to WHILE...WEND except that the test
completion is made at the end of the loop rather than the beginning.
The loop will be repeated continually until the specified condition is
FALSE. So it will always be performed at least once in your program.
Example:

        Repeat
          Print "AMOS Basic"
        Until Mouse Key<>0



                       DO...LOOP (loop forever)                             79

DO
:  :
list of statements
:  :
LOOP

The DO...LOOP commands take a list of Basic statements and repeat them
continually. In order to exit from this loop, you'll need to use a
special EXIT or EXIT IF instruction.

The advantage of this system is that it's a structure alternative to
the GOTO loops that tend to crop up in earlier versions of Basic. Take
the following example:

        TEST:
        Input "Another game (Y/N)";AN$
        If Upper$(AN$)="N" Then Goto BYE
        GAME : Rem call play game procedure
        Goto TEST
        BYE:
        End

Now a second version using DO...LOOP

        Do
          INput "Another game (Y/N)";AN$
          Exit If Upper$(AN$)="N"
          GAME : Rem call play game procedure
        Loop
        End



                     EXIT (Exit from a DO...LOOP)

EXIT [n]

The EXIT command exits immediately from one ore more program loops
created with the FOR...NEXT, REPEAT...UNTIL, WHILE...WEND, or DO...LOOP
statements. Your AMOS program will now jump directly to the next
instruction after the current loop.

  "n" is the numver of loops you wish to leave. If it's omitted, then
only the innermost loop will be terminated.



            EXIT IF (Exit from a loop depending on a test)                  80

EXIT IF expression[,n]

"expression" consistes of a series of tests in the standard AMOS
format. The EXIT will only be performed if the result evaluates to -1.

  The "n" parameter works the same way as using EXIT command.



           EDIT (stop running the prog and return to Editor)

EDIT

The EDIT directive stops the current program and returns to the AMOS
Basic editor. This can be very useful when you are debugging one of
your progs.



                     DIRECT (exit to direct mode)

DIRECT

Terminates your program and jumps to the direct mode immediately. You
can now examine the contents of your variables or list your programs
out to the printer.



                      END (Exit from the program)                           81

END

This instruction exits from a program. You'll now be given the option
to return to either the editor or to direct mode.



                   ON...PROC (jump to one of several
                  procedures depending on a variable)

ON v PROC proc1, proc2, proc3, ...procN

Jumps to a named procedure depending on the contents of variable v.
Note that any procedures you use in this command CANNOT include
parameters. If you need to transfer information to this procedure, you
should place them in *global* variables instead. See PROCEDURES for a
full explanation of this technique.

  The ON...PROC command is effectively equivalent to the following:

        If v=1 Then Proc1
        If v=2 Then Proc2
          :    :
        If v=n Then ProcN



               ON...GOTO (jump to one of a list of lines
                       depending on a variable)

ON v GOTO line1, line2, line3, ...lineN

The ON GOTO instruction lets your program jump to one of a number of
lines depending on the result of an expression in v. It's equivalent to
the following lines:

        If v=1 Then Goto Line1
        If v=2 Then Goto Line2
          :     :
        If v=n Then Goto LineN



                  ON...GOSUB (GOSUB one of a list of
                       routines dependig on var)

ON var GOSUB line1, line2, line3, ...

This is identical to ON...GOTO except it uses a gosub rather than a
goto to jump the line.



        EVERY n GOSUB (call a subroutine at regural intervals)              82

EVERY n GOSUB label

The ON EVERY statement calls the subroutine at label at regural
intervals, without interfering with your main program.

  "n" is the length of your interval in 50ths of a second. The time
taken for your subroutine to complete must always be less than this
period, or you'll get an error.

  After a subroutine has been entered, the system will automatically
disabled. In order to call this feature continuously, you'll therefore
need to add EVERY ON command before the final RETURN statement ;

        Every 50 Gosub TEST
        Do
          Print "Main loop"
        Loop
        TEST:
        Inc I : Print "This is call number ";I
        Every On:Return



         EVERY n PROC (call a procedure at regural intervals)

EVERY n PROC name

EVERY PROC execute the required procedure automatically at regular
intervals using a powerful interrupt system.

  "n" is the delay between each successive procedure call measured in
units of a 50th of a second.

  As with the previous command, the interrupt must be reactivated
before leaving your procedure, otherwise the routine will only be
called just once. So you'll need to use EVERY ON before returning to
your main program with END PROC ;

        Every 50 Proc TEST
        Do
          Print "Main loop"
        Loop
        Procedure TEST
          Shared I
          Inc I : Print "This is call number ";I
          Every On
        End Proc



            EVERY ON/OFF (toggle automatic procedure calls)

EVERY ON/OFF

EVERY ON restarts the interrupt system used by the EVERY commands. It
should be called just before the procedure or subroutine has finished
executing.

EVERY OFF disables the calls completely. It's automatically executed at
the start of one of these procedures.



            BREAK ON/OFF (turn on/off the CTRL+C Break key)                 83

BREAK ON/OFF

Normally you can interrupt a program and return to Basic at any time by
simply pressing CTRL+C. This function can be deactivated using the
BREAK OFF command. You can restart the Break keys using BREAK ON



Error handling
==============


           ON ERROR GOTO (trap an error within a Basic prog)

ON ERROR GOTO label

This command allows you to detect and correct the errors inside an AMOS
Basic program, without having to return to the editor window.
Sometimes, errors can arise in a program which are impossible to
predict in advance. Take, for instance, the following routine:

        Do
          Input "Enter two numbers";A,B
          Print A;" divided by ";B;" is ";A/B
        Loop

This program works fine until you try to enter a zero for B. You can
avoid the "division by zero error" by trapping the error with an ON
ERROR GOTO instruction like so:

        ON ERROR GOTO label

Whenever an error occurs in your Basic program, AMOS will now jump
straight to "label". This will be the starting point of your own error
correction routine which can fix the error and safely return to your
main program.

  Note that error handler MUST exit using a special RESUME instruction.
You are not allowed to jump back to your program with a normal GOTO
statement.

        On Error Goto HELP
        Do
          Input "Enter two numbers";A,B
          Print A;" divided by ";B;" is ";A/B
        Loop
        HELP:
        Print : Print : Bell
        Print "I'm afraid you've attempted to divide with zero!"
        Resume Next: Rem Return back to the next instruction.

In order for this system to work, it's essential that an error does not
arise inside your error correction routine, otherwise AMOS will halt
your program ignominiously.

  The action of ON ERROR GOTO can be disabled by calling ON ERROR with
no parameters.

        On Error : Rem Kill error traps



            ON ERROR PROC (Trap an error using a procedure)                 84

ON ERROR PROC name

Selects a procedure which will be called automatically if there's an
error in the main program. It's really just a structured version of the
ON ERROR GOTO statement.

  Although your procedure must be terminated by and END PROC in the
normal way, you'll need to return to your main program with an
additional call to RESUME. This can be placed just before the final END
PROC statement.



                RESUME (resume execution of the program                     85
                            after an error)

There are five possible formats of this instruction:

        RESUME

Jumps back to the statement which caused the error and tries again.

        RESUME NEXT

Returns to the instruction just after the one which caused the error.

        RESUME LINE

Jumps to as specific line point in your main program. "line" can refer
to either a label or a normal line number. This may *NOT* be used to
re-enter a procedure!

  Procedures are treated slightly differently. If you want to jump to a
particular label, you have to place a special marker somewhere in the
procedure you are checking for errors. This may be accomplished using
the RESUME LABEL command. There are two separate versions.

        RESUME LABEL label

Defines the label which is to be returned after an error. This must be
called outside your error handler just after the original ON ERROR PROC
or ON ERROR GOTO statement.

        RESUME LABEL

Used inside your error handler to jump straight back to the label
you've set up with the previous command. Example:

        On Error Proc HELP
        Resume Label AFTER
        Error 12
        Print "Never Printed"
        AFTER : Print "I've returned here"
        End
        Procedure HELP
          Print "Oh Dear, I think there's an error!"
          Resume Label
        Endproc



                =ERRN (return the number of last error)

e=ERRN

If you're creating your own error handling routines using the ON ERROR
command, you'll need to be able to check precisely which error has
occurred in the main program.

  When an error occurs, ERRN is automatically loaded with its
identification number. See the Apeendix at the end of this manual for a
full list of the possible errors.

        Print ERRN



          ERROR (generate an error and return to the Editor)

ERROR n

The action of the ERROR command is to actually generate an error.
Supposing you have created a nice little error handling routine which
is able to cope with all possible disc errors. ERROR provides you with
a simple way of simulating all the various problems, without the
inconvenience of the actual error. Example:

        Error 40

Quits the program and prints out a "Label not defined" error.

        Error Errn

This uses the ERRN function to print the current error condition after
a problem in your program.







                          8: TEXT AND WINDOWS                               87
                      ---------------------------

Text Attributes
===============

                       PEN (set colour of text)

PEN index

The PEN instruction sets the colour of all the text which will be
displayed in the current window. This colour can be chosen from one up
to 64 different possibilities depending on the gfx mode you're using.
Example:
          PEN 6



          =PEN$(n) (change the pen colour using ctrl chrars)

a$=PEN$(n)

PEN$ returns a special control sequence which changes the pen colour
inside a string. The new pen colour will be automatically assigned
whenever this string is subsequently printed on the screen. Example:

        C$=Pen$(2)+"White "+Pen$(6)+"Blue"
        Print C$

The string returned by PEN$ is in the format:
 Chr$(27)+"P"+Chr$(48+n)



               PAPER (set colour of the text background)

PAPER index

"index" can be a number between 0-63.



               =PAPER$(n) (return a control sequence to                     88
                         set the paper colour)

x$=PAPER$(index)

PAPER$ returns a character string which automatically changes the
background colour when it's printed on the screen. For example:

        Pen 1: C$=Paper$(2)+"White "+Paper$(6)+"Blue"
        Print C$



                  INVERSE ON/OFF (enter inverse mode)

INVERSE ON/OFF

The INVERSE command swaps the text and the background colours.



               SHADE ON/OFF (shade all subsequent text)

SHADE ON/OFF

SHADE ON highlights your text by reducing the brightness of the
characters with a mask pattern. The shade of your text can be returned
to normal using SHADE OFF



                   UNDER ON/OFF (set underline mode)                        89

UNDER ON/OFF

UNDER ON underlines your text when it's printed on the screen. UNDER
OFF turns off the mode.



                  WRITING (change text writing mode)

WRITING w1 [,w2]

The WRITING command allows you to change the writing mode used for all
subsequent text operations. This determines precisely how your new text
will be combined with the existing screen data.

        w1=0   REPLACE (Default)   Your new text will obliterate
                                   anything underneath it.
        w1=1   OR                  Merges the characters onto the
                                   screen with a logical OR.
        w1=2   XOR                 Chars are combined now with XOR.

        w1=3   IGNORE              Printing operations are ignored!

The secont number chooses which parts of the text will be printed on
the screen. This option can be omitted if required.

        w2=0   Normal       The text is output to the screen along with
                            the background.
        w2=1   Paper        Only the background of the text is drawn on
                            the screen.
        w2=2   Pen          Ignores the paper colour and writes the
                            text on a background of colour zero.

Do *NOT* confuse this with GR WRITING!



Cursor functions
================
AMOS includes a range of facilities which let you move cursor to any
part on the screen.



                     LOCATE (position the cursor)                           90

LOCATE x,y
LOCATE x,         Locate moves the text cursor to the coordinates x,y.
LOCATE ,y         This sets the starting point for all future printing
                  operations. All screen positions are specified using
a special set of text coordinates. These are meadured in units of a
single character relative to the top left corner of the text window.
For instance the coordinates 15,10 refer to a point 10 chars down and
15 to the right.

  If you attempt to print something outside window limits an error will
be generated.

  Note that the current screen is always treated as window 0. So you
don't have to actually open a window before using one of these
functions.



                   CMOVE (relative cursor movement)

CMOVE w,h

Moves the cursor a fixed distance away from its present position. If
your cursor was at 10,10, then typing:

        CMOVE 5,-5

would move the cursor to 15,5. Like LOCATE you can omit either one of
the coordinates as required.



                 =AT (return a sequence of ctrl chars                       91
                        to position the cursor)

x$=AT(x,y)

The AT function allows you to change the position of text directly from
inside a character string. It works by returning a string in the
format:
          Chr$(27)+"X"+Chr$(27)+"Y"+Chr$(48+Y)

Whenever this string is printed, the text cursor will be moved to the
coordinates x,y. For example:

      A$="This"+At(10,10)+"Is"+At(1,2)+"The Power Of"+At(20,20)+"AMOS!"
      Print A$

These AT commands are perfect for hi-score tables as they allow you to
position our text once and for all during your programs initialisation
phase. You can now update the score at the correct point on the screen
using a single print statement. Here's an example:

        HI_SCORE$=At(20,10)+"Hi Score "
        SCORE=10000
        Print HI_SCORE$;SCORE



Conversion functions
====================
AMOS Basic provides you with four useful functions which readliy enable
you to convert between text and graphics coordinates.



           =XTEXT (convert an x coordinate gfx->text format)                92
           =YTEXT (convert an y coordinate gfx->text format)

t=XTEXT(x)
t=YTEXT(y)

These functions take normal x/y coordinates and convert them to text
coordinates relative to the current window. If the screen coordinate
lies outside this window then a negative value will be returned. See
EXAMPLE 8.1.



         =XGRAPHIC (convert an x coordinate text->gfx format)
         =YGRAPHIC (convert an y coordinate text->gfx format)

g=XGRAPHIC(x)
g=XGRAPHIC(y)

These functions are effectively the inverse of XTEXT and YTEXT in that
they take a text X (or) Y coordinate ranging from 0 to the width/height
of the current window and convert them to absolute screen coordinates.
See EXAMPLE 8.2


Cursor commands
===============
The text cursor serves as a visible starting point of all future text
operations. It's usually displayed as a flashing horizontal bar,
although this may be changed using the SET CURS and CURS OFF commands.

  By moving the cursor on the screen, you can position your text
practically anywhere you like. Remember, all coordinate measurements
are taken using TEXT coordinates relative to the current window.



                          HOME (cursor home)

HOME

Moves the text cursor to the top left hand corner of the current window
(coordinates 0,0)



                          CDOWN (cursor down)                               93
CDOWN

Pushes the text cursor down by a single line.



                 =CDOWN$ (return a Chr$(31) character)
x$=CDOWN$

CDOWN$ is a function which returns a special control character which
automatically moves the cursor when it is printed. So Print CDOWN$ is
identical to CDOWN. CDOWN$ allows you to combine several cursor
movements in a single string. For example:

        C$="\"+Cdown$
        For A=0 to 20
          Print C$;
        Next A


                            CUP (cursor up)
CUP

Moves the text cursor up a line in the same way that CDOWN moves down.



                  =CUP$ (return a Chr$(30) character)
x$=CUP$

CUP$ returns a control string which moves the cursor up by a single
character.


                          CLEFT (cursor left)                               94
CLEFT

Displaces the text cursor one character to the left.



              =CLEFT$ (Control string for CLEFT Chr$(29))
x$=CLEFT$

Moves the text cursor one character left. Works like =CUP$.



                         CRIGHT (cursor right)
CRIGHT

Moves cursor one place to the right.



       =CRIGHT$ (Generate a Chr$(28) control string for CRIGHT)

x$=CRIGHT$

Is the opposite of CLEFT$.



          XCURS (return the X coordinate of the text cursor)
          YCURS (return the Y coordinate of the text cursor)                95

x=XCURS
y=YCURS

XCURS is a variable containing the current X coordinate of the text
cursos (in text format). YCURS holds the Y coordinate of the cursor.



                   SET CURS (set text cursor shape)

SET CURS L1,L2,L3,L4,L5,L6,L7,L8

This instructoin allows you to change the shape of the cursor to
anything you like. The shape is specified by a list of bit-patterns
held in the parameters L1-L8, Each parameter determines the appearance
of the horizontal line of the cursor, numbered from top to bottom.

  Every bit represnts a single point in the current cursor line. If
it's set to 1 then the point will be drawn using colour number 3 -
otherwise it will be displayed in the current PAPER colours. Example:

        L1=%11111111
        L2=%11111110
        L3=%11111100
        L4=%11111000
        L5=%11110000
        L6=%11100000
        L7=%11000000
        L8=%10000000
        Set Curs L1,L2,L3,L4,L5,L6,L7,L8



               CURS ON/OFF (enable/disable text cursor)

CURS ON                          makes text cursor visible
CURS OFF                         hides the cursor in current window



                     MEMORIZE X/Y (save the X or Y
                    coordinates of the text cursor)
MEMORIZE X
MEMORIZE Y
               The Memorize commands store the current cursor position.



                   REMEMBER X/Y (restore the X or Y                         96
                    coordinate of the text cursor)
REMEMBER X
REMEMBER Y
               REMEMBER positions the cursor at the coordinates saved
               by a previous call to MEMORIZE. If MEMORIZE has not been
          used then the coordinates will be set to zero. See EXAMPLE 8.3



         CLINE (clear part or all of the current cursor line)

CLINE [n]

Clears the line on which the cursor is positioned. If n is present then
"n" characters are cleared starting at the current cursor position.



          CURS PEN (choose a new colour for the text cursor)

CURS PEN n

Changes the colour of the text cursor to index number n.



Text Input/Output
=================


          CENTRE (print a line of text centred on the screen)

CENTRE a$

Takes a string of characters in a$ and prints it in the centre of the
screen. This text is always output on the current cursor line.

        Locate 0,1
        Centre "This is a centered TITLE"



                       =TAB$ (print tabulation)                             97

x$=TAB$

TAB$ returns a control character known as a TAB (Ascii 9). When this
character is printed the text cursor will be immediately moved several
places to the right. The size of this movement can be set using the SET
TAB kommand. As a default, the tab spacing is set to four (4).



                    SET TAB (change the tabulation)

SET TAB n

This specifies the distance the text cursor will move when TAB
character is printed.



                        REPEAT$ (repeat string)

x$=REPEAT$(a$,n)

The REPEAT$ function allows you to print out the same string of
characters several times using a single PRINT statement.

  It works by adding a sequenve of control characters into variable X$.
When this string is printed, AMOS simply repeats a$ to the screen n
times. Possible values for n range between 1 and 207. See EXAMPLE 8.4.

The format of the control string is:

        Chr$(27)+"RO"+A$+Chr$(27)+"R"+Chr$(48+n)


Advanced Text Commands                                                      98
======================


             ZONE$ (set up a zone around a piece of text)

x$=ZONE$(a$,n)

The ZONE$ function surrounds a section of text with a screen zone.
After you have defined one of these zones you can check for coillisions
between the zone and the mouse using the ZONE function. This allows you
to create powerful on-screen menus and dialogue boxes without having to
resort to any complicated programming tricks.

  a$ is a string containing the text for one the "Buttons" in your
dialogue box. This button will be activated automatically when you
print x$ to the screen.

  n specifies the number of screen zone to be defined. The max. number
of these zones depends on the value you specified with RESERVE ZONE.

  See the EXAMPLE 8.5 program in the MANUAL folder. The format of the
control string is:
                   Chr$(27)+"ZO"+A$+Chr$(27)+"R"+Chr$(48+n)



                  BORDER$ (add a border to some text)

x$=BORDER$(a$,n)

This returns a string of control characters which instructs AMOS to
draw a border aound the required text. It's commonly used in
conjunction with the ZONE$ command to produve the fancy buttons found
in dialogue boxes and alert windows.

  n is the border number ranging from 1 to 16 and a$ holds the text to
be enclosed by the border. The text in a$ will start at the current
cursor position so don't be surprised when you get strange results
printing at 0,0. To create a screen zone by a border try this:

        Print Border$(Zone$(" CLICK HERE ",1),2)

This would enclose the text with zone number 1 and border 2. The
control sequence is:
                     Chr$(27)+"EO"+A$+Chr$(27)+"R"+Chr$(48+n)



                  HSCROLL (horizontal text scrolling)

HSCROLL n

This scrolls all the text in the currently open window horizontally by
a single character position. n can take the following values:

        1 = Move current line to the left
        2 = Scrolls entire screen to the left
        3 = Move current line to the right
        4 = Move screen to the right



                       VSCROLL (vertival scroll)                            99

VSCROLL n

Scrolls the text in the currently open window vertically.

        1 = Any text at the cursor line and below is scrolled down
        2 = Text at cursor line or below is moved up
        3 = Only text from the top of the screen to the cursor line
             is scrolled up
        4 = Text from top of the screen to the current cursor position
             is scrolled down
                                              Blank lines are inserted
                     to pad out the gap left by the scrollingoperation.



Windows
=======
The AMOS windowing commands allow you to restrict your text and
graphics operations just a part of the current screen.

  AMOS windows can be used with the zone commands to produce effective
dialogue boxes such as file selectors and high score tables. A typical
warning box, for instance, can be easily generated with just a couple
lines of AMOS Basic.



                      WINDOPEN (create a window)

WINDOPEN n, x, y, w, h [,border [,set]]

The WINDOPEN instruction opens a window and displays it on the screen.
This window will now be used for all subsequent text operations.

  n is the number of the window to be defined. AMOS allows you to
create as many windows as you like, limited only by the amount of
available memory. As a default, window number zero is assigned to the
current screen. So don't attempt to re-open this window using WINDOPEN
or change it with WIND SIZE or WIND MOVE.

  x,y are the graphics coordinates of the top left hand corner of your
new window. Since AMOS windows are drawn using the Amiga's blitter
chip, the window area must always lie on a 16-pixel boundary. In order
to achieve this, the x coordinates are automatically rounded to the
nearest multiple of 16. Additionally, if you've included a border for
your window, the X coordinate will be incremented by a further eight.
This will ensure that the working area of your window always starts at
the correct screen boundary. There are no restrictions whatsoever on
the y coordinates.

  w,h specify the size in characters of the new window. These              100
dimensios must always be divisible by 2.

  "border" selects a border style for your window. There are 16
possible styles, with values ranging between 1 and 16.

  Window borders can also include up to two optional title lines. One
title is displayed along the top of the window and another may be added
at the bottom.

  AMOS windows may contain either text or graphics, just like the
intuition system. Each window can be assigned it's own individual
character set with the powerful WINDOW FONT command. There's also a
powerful WIND SAVE instuction which saves the screen area inside your
windows. Whenever you move one of these windows the contents underneath
will be automatically redrawn. For example:

        For W=1 To 3
          Windopen W,(W-1)*96,50,10,101
          Paper W+3 : Pen W+6 : Clw
          Print "Window ";W
        Next W

You can flick between these windows using the WINDOW command. Try
typing the following statements from the Direct mode:

        Window 1 : Print "AMOS"
        Window 3 : Print "in action!"
        Window 2 : Print "Basic"

The active window can always be distinguished by a flashing cursor -
through this can be turned off using the CURS OFF command if required.



                   WINDOW FONT (change window font)

WINDOW FONT n

Changes the font used by the current window to set n. n is the number
of a graphics font which has been previously installed with the GET
FONT command. This font *must* have dimensions of exactly 8x8.
Proportional fonts are not allowed.

  Since the window vborders make use of some of these characters, you
may get rather odd results when you're using standard WBench fonts.



          WIND SAVE (save the contents of the current window)

WIND SAVE

The WIND SAVE command allows you to move your windows anywhere on the
screen without corrputing your existing display.

  Once you've activated this feature, any windows you subsequently open
will automatically save the entire contents of the windows underneath.
This area will be redrawn whenever you close a window or move it to a
new position.

  It's important to note that this option saves the contents of the
current window, rather than the one you are defining with WIND OPEN.

  At the start of your program the current window will be the default
screen and will take up a massive 32k of memory. If you wished to save
the background underneath a dialogue box the most of this memory would
be completely wasted.

  The solution is to create a dummy window of the required size, and to
position it over the zone you wish to save. You can now execute a WIND
SAVE command and continue with your program as normal.

  When you subsequently call up your dialogue box the area underneath
will be saved as part of your dummy window. So it will be automatically
restored after your box has been removed.



               BORDER (change the window border of the)                    101
                            current screen)

BORDER n,paper,pen

The BORDER command sets the border of the current window to style
number n. This border is drawn using a group of characters installed in
the default font. It is therefore possible to create your own border
styles using the font definer accessory.

  The paper and pen options allow you to freely choose the colours of
your border. Acceptable border numbers range from 1 to 16.

  Any of the parameters may be omitted from this instuction so the
following commands are legal:

        BORDER 2,,
        BORDER 2,,3



                 TITLE TOP (define the upper title for
                          the current window)

TITLE TOP t$

This instruction sets the top line of the current window to the title
string in t$. Only bordered windows may be titled in this way.

        Windopen 5,1,1,20,10
        Title Top "Window Number 5"
        Wait Key



               TITLE BOTTOM (define the lower title for
                          the current window)

TITLE BOTTOM b$

This command assigns the string b$ to the bottom title of the current
window.



                      WINDOW (change current window)                       102

WINDOW n

WINDOW activates the window n as the current window. If the automatic
saving system has been initiated, this window be immediately redrawn
along with any of its contents. See EXAMPLE 8.6 in the Manual folder.



               =WINDON (Return the value current window)

w=WINDOW

WINDON returns the identification number of the currently active
window.



                 WIND CLOSE (close the current window)

WIND CLOSE

Deletes the current window. Use the WIND SAVE command if you want the
area that was hidden be redrawn by.



                       WIND MOVE (move a window)

WINDMOVE x,y

Windmove moves the current window to graphics coordinates x,y. As with
the original window definitions the x coordinate will be rounded to the
nearest 16-pixel boundary.



           WIND SIZE (change the size of the current window)               103

WIND SIZE sx,sy

This command changes the size of an AMOS window. The new sizes, sx and
sy, are specified in units of a single character. Sx must be divisible
by two. See EXAMPLE 8.7.

  If you've previously called the WIND SAVE command, the original
contents of your window will be redrawn by this instruction. If the new
window is smaller than the original one, any parts of the image which
lie outside will be lost. Alternatively, if you've expanded your
window, the area around your saved region will be filled with the
current paper colour. Also note that after a WIND SIZE command the text
cursor is always reset to coordinates 0,0.



                    CLW (clear the current window)

CLW

Erases the contents of the current window and fills it with the current
PAPER colour.


Slider bars                                                                104
===========
AMOS incorporates three insturctions which allow you to display a
standard slider bar on the screen. These sliders cannot be manipulated
directly with the mouse. In order to create a working slider bar,
you'll need to write a small Basic routine to perform this operate in
your main program. Due to the sheer power of the AMOS system, this is
extremely easy to accomplish, and the results can be extremely
impressive, as can be seen from EXAMPLE 8.8.



                  HSLIDER (draw a horizontal slider)

HSLIDER x1,y1 OT x2,y2,total,pos,size

Draws a horizontal slider bar from x1,y1 to x2,y2. "total" is the
number of individual units which the slider will be divided into. Each
unit represents a single item in the object you are controlling with
the slider. TSo in the editor window, "total" would be set to the
number of lines in the current program. The size of each unit is
calculated from the following formula:

        (X2-X1)/Total

"pos" is the position of the slider box from the start of the slider,
measured in the units you specified using "total". "size" is the length
of the slider box in the previous units. See EXAMPLE 8.9.



                   VSLIDER (draw a vertical slider)

VSLIDER x1,y1 TO x2,y2,total,pos,size

VSLIDER is almost identical to the previous HSLIDER insturction. It
displays a simple slider from x1,y1 to x2,y2. See EXAMPLE 8.10.



                  SET SLIDER (sets the fill patterns
                           used in a slider)

SET SLIDER b1,b2,b3,pb,s1,s2,s3,ps

Although this command looks incredibly complicated, it's actually
rather simple. SET SLIDER enters the colours and patterns to be used in
the slider bars created with the H/VSLIDER commands.

  "b1,b2,b3" set the ink, paper and outline colours for the background
of the box. "pb" chooses the fill pattern to be used for these regions.    105

  "s1,s2,s3" input the colours of the slider box, and "sp" selects the
pattern it is to be filled with.

  "bp" and "sp" can be any fill patterns you wish. As usual, negative
value refer to a sprite image from the current sprite bank. This allows
you to create amazing colorful slider boxes.


Fonts
=====
There are two different types of fonts available in AMOS - text fonts
and graphic fonts. The text fonts are those used by the PRINT and
WINDOW commands. Text fonts are known as character sets and each AMOS
Basic window can have its own individual set. The graphic fonts are
much more flexible and offer a wider range of styles:


Graphic text
============
Your Amiga computer is capable of displaying an impressive variety of
different text styles. The original WorkBench disc was supplied with
eight attractive fonts in a range of sizes, and many more of these
fonts are freely available from the public domain. If you've upgraded
to WorkBench 1.3, you'll also be able to design your own fonts using
the FED program on the Extras disc.

  AMOS provides you with total support for these fonts. Text can be
printed in any of the available typefaces at any point on the screen.

  AMOS fonts can be used to add spice to even the most Basic games.
These are invaluable for producing the loading screens and hi-score
tables in your games. So it's a good idea to make full use of them in
your progs.



                      TEXT (print graphical text)                          106

TEXT x,y,t$

TEXT prints a line of text in t$ at graphical coordinates x,y. All
coordinates are measured relative to the characters baseline. This can
be determined using a special TEXT BASE function.

  Normally the baseline is positioned at the bottom of the character,
but some lowercase letters, such as "g", have a "tail" which extends
slightly below this point.

  As a default the type styles is set to eight-point Topaz. This may be
changed at any time using the SET FONT instruction. Try the following
program and notice how text can be placed at any pixel position on the
screen.

  Do
    Ink Rnd(15)+1,Rnd(15): Text Rnd(320)+1,Rnd(198)+1,"AMOS Basic"
  Loop

Al so notice how the colour of your text is set with INK rather than
the expected PEN and PAPER commands. This emphasizes the fact that the
TEXT command is basically a graphical instruction. So the control
sequences created by functions like CUP$ will be printed on the screen
instead of being correctly interpreted.

  There is no automatic line feed when the text reaches the end of the
current window. If you attempt to print something too large, the text
will be neatly clipped at the existing screen boundary. This can be
seen by the example below:

        Print String$("A",100):Text 0,100,String$("A",100)



           GET FONTS (create a list of all available fonts)

GET FONTS

The GET FONTS command creates an internal list of the all fonts
available from the current start-up disc. This list is essential to the
running of the SET FONT command, so you should always call GET FONTS at
least once before attempting to change the present font setting. The
contents of this list can be examined using the FONT$ function.

  WARNING! In order for GET FONTS to work, your current AMOS work disc
must always contain a copy of the standard LIBS folder along with its
contents. It's important to remember this fact when you are
distributing run-only or compiled programs because unless your discs
contain the required files, AMOS Basic will almost certainly crash!



           GET DISC FONTS (create a list of the disc fonts)                107

GET DISC FONTS

This command is identical to the previous GET FONTS instruction except
that it only searches for fonts on the disc. These fonts are contained
in the FONTS folder on your current boot-disc. If you want to use your
own fonts with AMOS basic, you'll need to copy these onto your normal
start-up disc. See the manual supplied with your Amiga for details of
this procedure.



            GET ROM FONTS (create a list of the rom fonts)

GET ROM FONTS produces a list of the fonts which are built into Amiga's
rom chips. At the present time there are just two of these fonts:
Eight-point Topaz and nine-point Topaz.



           =FONT$ (return details about the available fonts)

a$=FONT$(n)

Returns a string of 38 chars which describes font number n. This
function allows you to examine the font list created by a previous call
to one of the GET FONT commands.

  a$ contains a list of characters which hold the name and type of your
font. If a font does not exist, a$ will be loaded a null value "",
otherwise a string will be returned in the following format:

        Character     Description                                          108
        ---------     -----------
           1-29       Font name
          30-33       Font height
          34-37       Identifier (set to either Disc or Rom)

See EXAMPLE 8.11!



                  SET FONT (choose a font for use by
                         the TEXT instruction)

SET FONT n

SET FONT changes the character set used by the TEXT command to font
number n. If the font is stored on the disc it will be automatically
loaded into your Amiga's memory. At the same time any previously sets
which are not in use will be removed. See EXAMPLE 8.12.



                       SET TEXT (set text style)

SET TEXT style

Allows you to change the style of a font. There are three styles to
choose from. "style" is a bit pattern in the following format:

        Bit  Effect
        ---  ------
         0   Underline        By setting the appropriate bits in this
         1   Bold             pattern you can choose between a total
         2   Italic           of eight different text styles.



              =TEXT STYLE (return the current text style)                  109

s=TEXT STYLE

This function returns the text style set from the SET TEXT command. The
result in "s" is a bit-map in the same format as that used by SET TEXT.



             =TEXT LENGTH (return the length of a section
                           of graphic text)

w=TEXT LENGTH(t$)

The TEXT LENGTH function returns the width in pixels of the character
string a$ in the current font. The width of a character varies
depending on the size of your fonts. In addition, proportional fonts
such as Helvetica assign different widths for each individual
character.



               =TEXT BASE (return the current text base)

b=TEXT BASE

This function returns the position of the baseline of your font. The
baseline is the number of pixels between the top of a character and
point it will be printed on the screen. It's basically similar to the
hot spot of a sprite or bob.


Installing new fonts
====================
If you wish to use your own fonts within AMOS Basic, you'll need to
install them onto a copy of your AMOS program disc. The basic procedure
is as follows:

 - Copy the required font files into the FONTS: directory of your boot-
   disc.
 - Further information can be found in the Extra's manual supplied with
   the Workbench 1.3 upgrade.


Troubleshooting
===============

Problem:  GET FONTS seems to ignore any of the fonts on the current        110
          disc.
Solution: You've propably removed the original boot disc from your
          default drive. The Amiga's library routines expect to find
          the FONTS: directory on your start-up disc. This can be
          changed using the ASSIGN program in the UTILITIES folder.

Problem:  GET FONTS crahes the Amiga completely.
Solution: This problem can easily occur when you're creating programs
          in run-only or compiled format. GET FONTS requires the
          discfont.library in the LIBS folder in order to work.

Problem:  The SET FONT command returns a "fonts not examined" error.
Solution: Add a cal to GET FONTS to the start of your program.